home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / gaim / accountopt.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-18  |  9.4 KB  |  351 lines
  1. /**
  2.  * @file accountopt.h Account Options API
  3.  * @ingroup core
  4.  *
  5.  * gaim
  6.  *
  7.  * Gaim is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25. #ifndef _GAIM_ACCOUNTOPT_H_
  26. #define _GAIM_ACCOUNTOPT_H_
  27.  
  28. #include "prefs.h"
  29.  
  30. /**
  31.  * An option for an account.
  32.  *
  33.  * This is set by protocol plugins, and appears in the account settings
  34.  * dialogs.
  35.  */
  36. typedef struct
  37. {
  38.     GaimPrefType type;      /**< The type of value.                     */
  39.  
  40.     char *text;             /**< The text that will appear to the user. */
  41.     char *pref_name;        /**< The name of the associated preference. */
  42.  
  43.     union
  44.     {
  45.         gboolean boolean;   /**< The default boolean value.             */
  46.         int integer;        /**< The default integer value.             */
  47.         char *string;       /**< The default string value.              */
  48.         GList *list;        /**< The default list value.                */
  49.  
  50.     } default_value;
  51.  
  52.     gboolean masked;
  53.  
  54. } GaimAccountOption;
  55.  
  56. /**
  57.  * A username split.
  58.  *
  59.  * This is used by some protocols to separate the fields of the username
  60.  * into more human-readable components.
  61.  */
  62. typedef struct
  63. {
  64.     char *text;             /**< The text that will appear to the user. */
  65.     char *default_value;    /**< The default value.                     */
  66.     char  field_sep;        /**< The field separator.                   */
  67.  
  68. } GaimAccountUserSplit;
  69.  
  70. #ifdef __cplusplus
  71. extern "C" {
  72. #endif
  73.  
  74. /**************************************************************************/
  75. /** @name Account Option API                                              */
  76. /**************************************************************************/
  77. /*@{*/
  78.  
  79. /**
  80.  * Creates a new account option.
  81.  *
  82.  * @param type      The type of option.
  83.  * @param text      The text of the option.
  84.  * @param pref_name The account preference name for the option.
  85.  *
  86.  * @return The account option.
  87.  */
  88. GaimAccountOption *gaim_account_option_new(GaimPrefType type, const char *text,
  89.                                            const char *pref_name);
  90.  
  91. /**
  92.  * Creates a new boolean account option.
  93.  *
  94.  * @param text          The text of the option.
  95.  * @param pref_name     The account preference name for the option.
  96.  * @param default_value The default value.
  97.  *
  98.  * @return The account option.
  99.  */
  100. GaimAccountOption *gaim_account_option_bool_new(const char *text,
  101.                                                 const char *pref_name,
  102.                                                 gboolean default_value);
  103.  
  104. /**
  105.  * Creates a new integer account option.
  106.  *
  107.  * @param text          The text of the option.
  108.  * @param pref_name     The account preference name for the option.
  109.  * @param default_value The default value.
  110.  *
  111.  * @return The account option.
  112.  */
  113. GaimAccountOption *gaim_account_option_int_new(const char *text,
  114.                                                const char *pref_name,
  115.                                                int default_value);
  116.  
  117. /**
  118.  * Creates a new string account option.
  119.  *
  120.  * @param text          The text of the option.
  121.  * @param pref_name     The account preference name for the option.
  122.  * @param default_value The default value.
  123.  *
  124.  * @return The account option.
  125.  */
  126. GaimAccountOption *gaim_account_option_string_new(const char *text,
  127.                                                   const char *pref_name,
  128.                                                   const char *default_value);
  129.  
  130. /**
  131.  * Creates a new list account option.
  132.  *
  133.  * The list passed will be owned by the account option, and the
  134.  * strings inside will be freed automatically.
  135.  *
  136.  * The list is in key, value pairs. The key is the ID stored and used
  137.  * internally, and the value is the label displayed.
  138.  *
  139.  * @param text      The text of the option.
  140.  * @param pref_name The account preference name for the option.
  141.  * @param list      The key, value list.
  142.  *
  143.  * @return The account option.
  144.  */
  145. GaimAccountOption *gaim_account_option_list_new(const char *text,
  146.                                                 const char *pref_name,
  147.                                                 GList *list);
  148.  
  149. /**
  150.  * Destroys an account option.
  151.  *
  152.  * @param option The option to destroy.
  153.  */
  154. void gaim_account_option_destroy(GaimAccountOption *option);
  155.  
  156. /**
  157.  * Sets the default boolean value for an account option.
  158.  *
  159.  * @param option The account option.
  160.  * @param value  The default boolean value.
  161.  */
  162. void gaim_account_option_set_default_bool(GaimAccountOption *option,
  163.                                           gboolean value);
  164.  
  165. /**
  166.  * Sets the default integer value for an account option.
  167.  *
  168.  * @param option The account option.
  169.  * @param value  The default integer value.
  170.  */
  171. void gaim_account_option_set_default_int(GaimAccountOption *option,
  172.                                          int value);
  173.  
  174. /**
  175.  * Sets the default string value for an account option.
  176.  *
  177.  * @param option The account option.
  178.  * @param value  The default string value.
  179.  */
  180. void gaim_account_option_set_default_string(GaimAccountOption *option,
  181.                                             const char *value);
  182.  
  183. /**
  184.  * Sets the masking for an account option.
  185.  *
  186.  * @param option The account option.
  187.  * @param masked  The masking.
  188.  */
  189. void gaim_account_option_set_masked(GaimAccountOption *option, gboolean masked);
  190.  
  191. /**
  192.  * Sets the list values for an account option.
  193.  *
  194.  * The list passed will be owned by the account option, and the
  195.  * strings inside will be freed automatically.
  196.  *
  197.  * The list is in key, value pairs. The key is the ID stored and used
  198.  * internally, and the value is the label displayed.
  199.  *
  200.  * @param option The account option.
  201.  * @param values The default list value.
  202.  */
  203. void gaim_account_option_set_list(GaimAccountOption *option, GList *values);
  204.  
  205. /**
  206.  * Adds an item to a list account option.
  207.  *
  208.  * @param option The account option.
  209.  * @param key    The key.
  210.  * @param value  The value.
  211.  */
  212. void gaim_account_option_add_list_item(GaimAccountOption *option,
  213.                                        const char *key, const char *value);
  214.  
  215. /**
  216.  * Returns the specified account option's type.
  217.  *
  218.  * @param option The account option.
  219.  *
  220.  * @return The account option's type.
  221.  */
  222. GaimPrefType gaim_account_option_get_type(const GaimAccountOption *option);
  223.  
  224. /**
  225.  * Returns the text for an account option.
  226.  *
  227.  * @param option The accont option.
  228.  *
  229.  * @return The account option's text.
  230.  */
  231. const char *gaim_account_option_get_text(const GaimAccountOption *option);
  232.  
  233. /**
  234.  * Returns the account setting for an account option.
  235.  *
  236.  * @param option The accont option.
  237.  *
  238.  * @return The account setting.
  239.  */
  240. const char *gaim_account_option_get_setting(const GaimAccountOption *option);
  241.  
  242. /**
  243.  * Returns the default boolean value for an account option.
  244.  *
  245.  * @param option The account option.
  246.  *
  247.  * @return The default boolean value.
  248.  */
  249. gboolean gaim_account_option_get_default_bool(const GaimAccountOption *option);
  250.  
  251. /**
  252.  * Returns the default integer value for an account option.
  253.  *
  254.  * @param option The account option.
  255.  *
  256.  * @return The default integer value.
  257.  */
  258. int gaim_account_option_get_default_int(const GaimAccountOption *option);
  259.  
  260. /**
  261.  * Returns the default string value for an account option.
  262.  *
  263.  * @param option The account option.
  264.  *
  265.  * @return The default string value.
  266.  */
  267. const char *gaim_account_option_get_default_string(
  268.     const GaimAccountOption *option);
  269.  
  270. /**
  271.  * Returns the masking for an account option.
  272.  *
  273.  * @param option The account option.
  274.  *
  275.  * @return The masking.
  276.  */
  277. gboolean gaim_account_option_get_masked(const GaimAccountOption *option);
  278.  
  279. /**
  280.  * Returns the list values for an account option.
  281.  *
  282.  * @param option The account option.
  283.  *
  284.  * @return The list values.
  285.  */
  286. const GList *gaim_account_option_get_list(const GaimAccountOption *option);
  287.  
  288. /*@}*/
  289.  
  290.  
  291. /**************************************************************************/
  292. /** @name Account User Split API                                          */
  293. /**************************************************************************/
  294. /*@{*/
  295.  
  296. /**
  297.  * Creates a new account username split.
  298.  *
  299.  * @param text          The text of the option.
  300.  * @param default_value The default value.
  301.  * @param sep           The field separator.
  302.  *
  303.  * @return The new user split.
  304.  */
  305. GaimAccountUserSplit *gaim_account_user_split_new(const char *text,
  306.                                                   const char *default_value,
  307.                                                   char sep);
  308.  
  309. /**
  310.  * Destroys an account username split.
  311.  *
  312.  * @param split The split to destroy.
  313.  */
  314. void gaim_account_user_split_destroy(GaimAccountUserSplit *split);
  315.  
  316. /**
  317.  * Returns the text for an account username split.
  318.  *
  319.  * @param split The account username split.
  320.  *
  321.  * @return The account username split's text.
  322.  */
  323. const char *gaim_account_user_split_get_text(const GaimAccountUserSplit *split);
  324.  
  325. /**
  326.  * Returns the default string value for an account split.
  327.  *
  328.  * @param split The account username split.
  329.  *
  330.  * @return The default string.
  331.  */
  332. const char *gaim_account_user_split_get_default_value(
  333.         const GaimAccountUserSplit *split);
  334.  
  335. /**
  336.  * Returns the field separator for an account split.
  337.  *
  338.  * @param split The account username split.
  339.  *
  340.  * @return The field separator.
  341.  */
  342. char gaim_account_user_split_get_separator(const GaimAccountUserSplit *split);
  343.  
  344. /*@}*/
  345.  
  346. #ifdef __cplusplus
  347. }
  348. #endif
  349.  
  350. #endif /* _GAIM_ACCOUNTOPT_H_ */
  351.